<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
  <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Debugging &mdash; The Logtalk Handbook v3.93.0-b01 documentation</title>
      <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=d75fae25" />
      <link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=19f00094" />
      <link rel="stylesheet" type="text/css" href="../_static/css/custom.css?v=396eccfe" />

  
  <!--[if lt IE 9]>
    <script src="../_static/js/html5shiv.min.js"></script>
  <![endif]-->
  
        <script src="../_static/jquery.js?v=5d32c60e"></script>
        <script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
        <script src="../_static/documentation_options.js?v=c8100655"></script>
        <script src="../_static/doctools.js?v=9a2dae69"></script>
        <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../_static/js/theme.js"></script>
    <!-- begin favicon -->
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
    <link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png" />
    <link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
    <link rel="manifest" href="/site.webmanifest" />
    <link rel="mask-icon" href="/safari-pinned-tab.svg" color="#5bbad5" />
    <meta name="msapplication-TileColor" content="#355b95" />
    <meta name="theme-color" content="#ffffff" />
    <!-- end favicon -->
    
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="Performance" href="performance.html" />
    <link rel="prev" title="Documenting" href="documenting.html" />
   
</head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="../index.html" class="icon icon-home">
            The Logtalk Handbook
              <img src="../_static/logtalk.gif" class="logo" alt="Logo"/>
          </a>
              <div class="version">
                3.93.0
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
    
              <p class="caption" role="heading"><span class="caption-text">Contents</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="index.html">User Manual</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="declarative.html">Declarative object-oriented programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="features.html">Main features</a></li>
<li class="toctree-l2"><a class="reference internal" href="nomenclature.html">Nomenclature</a></li>
<li class="toctree-l2"><a class="reference internal" href="messages.html">Messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="objects.html">Objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="protocols.html">Protocols</a></li>
<li class="toctree-l2"><a class="reference internal" href="categories.html">Categories</a></li>
<li class="toctree-l2"><a class="reference internal" href="predicates.html">Predicates</a></li>
<li class="toctree-l2"><a class="reference internal" href="inheritance.html">Inheritance</a></li>
<li class="toctree-l2"><a class="reference internal" href="events.html">Event-driven programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="threads.html">Multi-threading programming</a></li>
<li class="toctree-l2"><a class="reference internal" href="errors.html">Error handling</a></li>
<li class="toctree-l2"><a class="reference internal" href="reflection.html">Reflection</a></li>
<li class="toctree-l2"><a class="reference internal" href="programming.html">Writing and running applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="printing.html">Printing messages and asking questions</a></li>
<li class="toctree-l2"><a class="reference internal" href="expansion.html">Term and goal expansion</a></li>
<li class="toctree-l2"><a class="reference internal" href="documenting.html">Documenting</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Debugging</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#compiling-source-files-in-debug-mode">Compiling source files in debug mode</a></li>
<li class="toctree-l3"><a class="reference internal" href="#procedure-box-model">Procedure box model</a></li>
<li class="toctree-l3"><a class="reference internal" href="#activating-the-debugger">Activating the debugger</a></li>
<li class="toctree-l3"><a class="reference internal" href="#defining-breakpoints">Defining breakpoints</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#defining-predicate-and-clause-breakpoints">Defining predicate and clause breakpoints</a></li>
<li class="toctree-l4"><a class="reference internal" href="#defining-conditional-breakpoints">Defining conditional breakpoints</a></li>
<li class="toctree-l4"><a class="reference internal" href="#defining-hit-count-breakpoints">Defining hit count breakpoints</a></li>
<li class="toctree-l4"><a class="reference internal" href="#defining-triggered-breakpoints">Defining triggered breakpoints</a></li>
<li class="toctree-l4"><a class="reference internal" href="#defining-context-breakpoints">Defining context breakpoints</a></li>
<li class="toctree-l4"><a class="reference internal" href="#removing-all-breakpoints">Removing all breakpoints</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#defining-log-points">Defining log points</a></li>
<li class="toctree-l3"><a class="reference internal" href="#tracing-program-execution">Tracing program execution</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debugging-using-breakpoints">Debugging using breakpoints</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debugging-commands">Debugging commands</a></li>
<li class="toctree-l3"><a class="reference internal" href="#customizing-term-writing">Customizing term writing</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#term-write-depth">Term write depth</a></li>
<li class="toctree-l4"><a class="reference internal" href="#custom-term-writing">Custom term writing</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#context-switching-calls">Context-switching calls</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debugging-messages">Debugging messages</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#meta-messages">Meta-messages</a></li>
<li class="toctree-l4"><a class="reference internal" href="#selective-printing-of-debug-messages">Selective printing of debug messages</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#using-the-term-expansion-mechanism-for-debugging">Using the term-expansion mechanism for debugging</a></li>
<li class="toctree-l3"><a class="reference internal" href="#ports-profiling">Ports profiling</a></li>
<li class="toctree-l3"><a class="reference internal" href="#debug-and-trace-events">Debug and trace events</a></li>
<li class="toctree-l3"><a class="reference internal" href="#source-level-debugger">Source-level debugger</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="performance.html">Performance</a></li>
<li class="toctree-l2"><a class="reference internal" href="installing.html">Installing Logtalk</a></li>
<li class="toctree-l2"><a class="reference internal" href="migration.html">Prolog integration and migration</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../refman/index.html">Reference Manual</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/index.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devtools/index.html">Developer Tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../libraries/index.html">Libraries</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ports/index.html">Ports</a></li>
<li class="toctree-l1"><a class="reference internal" href="../contributions/index.html">Contributions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="../genindex.html">Index</a></li>
</ul>

    <p class="caption"><span class="caption-text">External Contents</span></p>
    <ul>
    <li class="toctree-l1"><a class="reference internal" href="../../apis/index.html">APIs</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://logtalk.org">Logtalk website</a></li>
    <li class="toctree-l1"><a class="reference internal" href="https://github.com/LogtalkDotOrg/logtalk3">GitHub repo</a></li>
    </ul>
  
        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="../index.html">The Logtalk Handbook</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
          <li class="breadcrumb-item"><a href="index.html">User Manual</a></li>
      <li class="breadcrumb-item active">Debugging</li>
      <li class="wy-breadcrumbs-aside">
              <a href="https://github.com/LogtalkDotOrg/logtalk3/blob/master/docs/handbook/sources/userman/debugging.rst" class="fa fa-github"> Edit on GitHub</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="debugging">
<span id="debugging-debugging"></span><h1>Debugging<a class="headerlink" href="#debugging" title="Link to this heading"></a></h1>
<p>The Logtalk distribution includes a command-line <a class="reference internal" href="../devtools/debugger.html"><span class="doc">debugger</span></a>
tool implemented as a Logtalk application using the debugging API. It can be
loaded at the top-level interpreter by typing:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- logtalk_load(debugger(loader)).
</pre></div>
</div>
<p>It can also be loaded automatically at startup time by using a
<a class="reference internal" href="../glossary.html#term-settings-file"><span class="xref std std-term">settings file</span></a>.</p>
<p>The <a class="reference internal" href="../devtools/debugger.html"><span class="doc">debugger</span></a> tool includes the debugging features found
in traditional Prolog debuggers. There are some differences, however, between
the usual implementation of Prolog debuggers and the current implementation
of the Logtalk debugger that you should be aware of. First, unlike most Prolog
debuggers, the Logtalk debugger is not a built-in feature but a regular
Logtalk application using documented debugging hook predicates. This
translates to a different, although similar, set of debugging features
when compared with some of the more sophisticated Prolog debuggers. Second,
debugging is only possible for entities compiled in debug mode. When
compiling an entity in debug mode, Logtalk decorates clauses with source
information to allow tracing of the goal execution. Third, the tool
provides several types of breakpoints (for pausing and interacting with
the debugger) and also log points, while most Prolog systems are limited
to traditional predicate spy points.</p>
<section id="compiling-source-files-in-debug-mode">
<span id="debugging-debug-mode"></span><h2>Compiling source files in debug mode<a class="headerlink" href="#compiling-source-files-in-debug-mode" title="Link to this heading"></a></h2>
<p>Compilation of source files in debug mode is controlled by the
<a class="reference internal" href="programming.html#flag-debug"><span class="std std-ref">debug</span></a> compiler flag. The default value for this flag,
usually <code class="docutils literal notranslate"><span class="pre">off</span></code>, is defined in the adapter files. Its default value may
be changed globally at runtime by calling:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- set_logtalk_flag(debug, on).
</pre></div>
</div>
<p>Implicitly, this goal also turns off the <code class="docutils literal notranslate"><span class="pre">optimize</span></code> flag. In alternative,
if we want to compile only some source files in debug mode, we may instead
write:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- logtalk_load([file1, file2, ...], [debug(on)]).
</pre></div>
</div>
<p>The <a class="reference internal" href="../refman/predicates/logtalk_make_1.html#predicates-logtalk-make-1"><span class="std std-ref">logtalk_make/1</span></a> built-in predicate can also be used to
recompile all loaded files (that were compiled without using explicit values
for the <a class="reference internal" href="programming.html#flag-debug"><span class="std std-ref">debug</span></a> and <a class="reference internal" href="programming.html#flag-optimize"><span class="std std-ref">optimize</span></a> compiler
flags in a <code class="docutils literal notranslate"><span class="pre">logtalk_load/2</span></code> call or in a <a class="reference internal" href="../glossary.html#term-loader-file"><span class="xref std std-term">loader file</span></a>, if used)
in debug mode:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- logtalk_make(debug).
</pre></div>
</div>
<p>With most <a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compilers</span></a>, the
<code class="docutils literal notranslate"><span class="pre">{+d}</span></code> top-level shortcut can also be used. After debugging, the files can
be recompiled in normal or optimized mode using, respectively, the <code class="docutils literal notranslate"><span class="pre">{+n}</span></code>
or <code class="docutils literal notranslate"><span class="pre">{+o}</span></code> top-level shortcuts.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>The <a class="reference internal" href="programming.html#flag-clean"><span class="std std-ref">clean</span></a> compiler flag should be turned on whenever
the <a class="reference internal" href="programming.html#flag-debug"><span class="std std-ref">debug</span></a> flag is turned on at runtime. This is necessary
because debug code would not be generated for files previously compiled in
normal or optimized mode if there are no changes to the source files.</p>
</div>
<p>After loading the debugger, we may check (or enumerate by backtracking),
all loaded entities compiled in debug mode as follows:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::debugging(Entity).
</pre></div>
</div>
<p>To compile only a specific entity in debug mode, use the
<a class="reference internal" href="../refman/directives/set_logtalk_flag_2.html#directives-set-logtalk-flag-2"><span class="std std-ref">set_logtalk_flag/2</span></a> directive inside the entity.
To compile all entities in a source file in debug mode, use the
<a class="reference internal" href="../refman/directives/set_logtalk_flag_2.html#directives-set-logtalk-flag-2"><span class="std std-ref">set_logtalk_flag/2</span></a> directive at the beginning
of the file.</p>
</section>
<section id="procedure-box-model">
<span id="debugging-box-model"></span><h2>Procedure box model<a class="headerlink" href="#procedure-box-model" title="Link to this heading"></a></h2>
<p>Logtalk uses a <em>procedure box model</em> similar to those found on most
Prolog systems. The traditional Prolog procedure box model defines
four ports (<em>call</em>, <em>exit</em>, <em>redo</em>, and <em>fail</em>) for describing control
flow when calling a predicate:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">call</span></code></div>
<div class="line-block">
<div class="line">predicate call</div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">exit</span></code></div>
<div class="line-block">
<div class="line">success of a predicate call</div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">redo</span></code></div>
<div class="line-block">
<div class="line">backtracking into a predicate</div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">fail</span></code></div>
<div class="line-block">
<div class="line">failure of a predicate call</div>
</div>
</div>
<p>Logtalk, as found on some recent Prolog systems, adds a port for dealing
with exceptions thrown when calling a predicate:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">exception</span></code></div>
<div class="line-block">
<div class="line">predicate call throws an exception</div>
</div>
</div>
<p>In addition to the ports described above, Logtalk adds two more ports,
<code class="docutils literal notranslate"><span class="pre">fact</span></code> and <code class="docutils literal notranslate"><span class="pre">rule</span></code>, which show the result of the unification of a
goal with, respectively, a fact and a rule head:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">fact</span></code></div>
<div class="line-block">
<div class="line">unification success between a goal and a fact</div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">rule</span></code></div>
<div class="line-block">
<div class="line">unification success between a goal and a rule head</div>
</div>
</div>
<p>Following Prolog tradition, the user may define for which ports the
debugger should pause for user interaction by specifying a list of
<em>leashed</em> ports. Unleashed ports are just printed with no pause for
user interaction when tracing. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::leash([call, exit, fail]).
</pre></div>
</div>
<p>Alternatively, the user may use an atom abbreviation for a pre-defined
set of ports. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::leash(loose).
</pre></div>
</div>
<p>The abbreviations defined in Logtalk are similar to those defined on
some Prolog compilers:</p>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">none</span></code></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[]</span></code></div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">loose</span></code></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[fact,</span> <span class="pre">rule,</span> <span class="pre">call]</span></code></div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">half</span></code></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[fact,</span> <span class="pre">rule,</span> <span class="pre">call,</span> <span class="pre">redo]</span></code></div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">tight</span></code></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[fact,</span> <span class="pre">rule,</span> <span class="pre">call,</span> <span class="pre">redo,</span> <span class="pre">fail,</span> <span class="pre">exception]</span></code></div>
</div>
<div class="line"><code class="docutils literal notranslate"><span class="pre">full</span></code></div>
<div class="line-block">
<div class="line"><code class="docutils literal notranslate"><span class="pre">[fact,</span> <span class="pre">rule,</span> <span class="pre">call,</span> <span class="pre">exit,</span> <span class="pre">redo,</span> <span class="pre">fail,</span> <span class="pre">exception]</span></code></div>
</div>
</div>
<p>By default, the debugger pauses at every port for user interaction.</p>
</section>
<section id="activating-the-debugger">
<h2>Activating the debugger<a class="headerlink" href="#activating-the-debugger" title="Link to this heading"></a></h2>
<p>The <a class="reference external" href="../../apis/debuggerp_0.html#debuggerp-0-trace-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">debuggerp::trace/0</span></a> and
<a class="reference external" href="../../apis/debuggerp_0.html#debuggerp-0-debug-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">debuggerp::debug/0</span></a> predicates implicitly
select the <code class="docutils literal notranslate"><span class="pre">debugger</span></code> tool as the active debug handler. If you have additional
debug handlers loaded (e.g., the <code class="docutils literal notranslate"><span class="pre">ports_profiler</span></code> tool), those would no longer
be active (there can be only one active debug handler at any given time). The
<a class="reference external" href="../../apis/debuggerp_0.html#debuggerp-0-nodebug-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">debuggerp::nodebug/0</span></a> predicate implicitly
deselects the <code class="docutils literal notranslate"><span class="pre">debugger</span></code> tool as the active debug handler.</p>
</section>
<section id="defining-breakpoints">
<h2>Defining breakpoints<a class="headerlink" href="#defining-breakpoints" title="Link to this heading"></a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">debugger</span></code> tool provides the following breakpoint types where the debugger
pauses at a leashed port for user interaction:</p>
<ul class="simple">
<li><dl class="simple">
<dt>Predicate breakpoints</dt><dd><p>Traditional Prolog spy points are defined using a predicate (or a non-terminal)
indicator.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Clause breakpoints</dt><dd><p>Defined using the location of a clause.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Conditional breakpoints</dt><dd><p>Defined using the location of a clause and a condition for pausing.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Hit count breakpoints</dt><dd><p>Defined using the location of a clause and an unification count expression
as a condition for pausing.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Triggered breakpoints</dt><dd><p>Defined using the location of a clause and another breakpoint that must be
hit first as a condition for pausing.</p>
</dd>
</dl>
</li>
<li><dl class="simple">
<dt>Context breakpoints</dt><dd><p>Defined using execution context and goal templates as a condition for
pausing.</p>
</dd>
</dl>
</li>
</ul>
<p>Clause breakpoints are checked when the current goal successfully unifies
with a clause head. To simplify their definition, these are specified using
the entity identifier instead of the file name (as all entities share a single
namespace, an entity can only be defined in a single file) and the first line
number of the clause head. But note that only some Prolog backends provide
accurate source file term line numbers. Check the <a class="reference internal" href="../devtools/debugger.html"><span class="doc">debugger</span></a>
tool documentation for details.</p>
<section id="defining-predicate-and-clause-breakpoints">
<h3>Defining predicate and clause breakpoints<a class="headerlink" href="#defining-predicate-and-clause-breakpoints" title="Link to this heading"></a></h3>
<p>Predicate and clause breakpoints can be defined using the debugger <code class="docutils literal notranslate"><span class="pre">spy/1</span></code>
predicate. The argument can be a predicate indicator (<code class="docutils literal notranslate"><span class="pre">Name/Arity</span></code>), a
non-terminal indicator (<code class="docutils literal notranslate"><span class="pre">Name//Arity</span></code>), a clause location (expressed as
an <code class="docutils literal notranslate"><span class="pre">Entity-Line</span></code> pair), or a list of breakpoints. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(person-42).

All specified breakpoints added.
yes

| ?- debugger::spy(foo/2).

All specified breakpoints added.
yes

| ?- debugger::spy([foo/4, bar//1, agent-99]).

All specified breakpoints added.
yes
</pre></div>
</div>
<p>Note that setting a clause breakpoint implicitly removes any existing
conditional breakpoint, triggered breakpoint, or log point for the same
clause.</p>
<p>Unconditional clause and predicate breakpoints can be removed by
using the debugger <code class="docutils literal notranslate"><span class="pre">nospy/1</span></code> predicate. The argument can also be a list
of breakpoints or a non-instantiated variable, in which case all breakpoints
will be removed. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::nospy(_).

All matching predicate and clause breakpoints removed.
yes
</pre></div>
</div>
</section>
<section id="defining-conditional-breakpoints">
<h3>Defining conditional breakpoints<a class="headerlink" href="#defining-conditional-breakpoints" title="Link to this heading"></a></h3>
<p>Conditional clause breakpoints are specified using the debugger <code class="docutils literal notranslate"><span class="pre">spy/3</span></code>
predicate. The condition can be a lambda expression, an unification count
expression (see next section), or another breakpoint (see next section).</p>
<p>The supported lambda expressions are <code class="docutils literal notranslate"><span class="pre">[Count,</span> <span class="pre">N,</span> <span class="pre">Goal]&gt;&gt;Condition</span></code> and
<code class="docutils literal notranslate"><span class="pre">[Goal]&gt;&gt;Condition</span></code> where <code class="docutils literal notranslate"><span class="pre">Count</span></code> is the unification count, <code class="docutils literal notranslate"><span class="pre">N</span></code> is the
goal invocation number, and <code class="docutils literal notranslate"><span class="pre">Goal</span></code> is the goal that unified with the clause
head; <code class="docutils literal notranslate"><span class="pre">Condition</span></code> is called in the context of the <code class="docutils literal notranslate"><span class="pre">user</span></code> pseudo-object and
must not have any side effects. Some examples:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(planet, 76, [weight(m1,_)]&gt;&gt;true).

Conditional breakpoint added.
yes
</pre></div>
</div>
<p>Note that setting a conditional breakpoint will remove any existing clause
breakpoint or log point for the same location.</p>
<p>Conditional breakpoints can be removed by using the debugger <code class="docutils literal notranslate"><span class="pre">nospy/3</span></code>
predicate. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::nospy(planet, _, _).

All matching conditional breakpoints removed.
yes
</pre></div>
</div>
</section>
<section id="defining-hit-count-breakpoints">
<h3>Defining hit count breakpoints<a class="headerlink" href="#defining-hit-count-breakpoints" title="Link to this heading"></a></h3>
<p>Conditional clause breakpoints that depend on the unification count are
known as <em>hit count</em> clause breakpoints. The debugger pauses at a hit
count breakpoint depending on an unification count expression:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">&gt;(Count)</span></code> - break when the unification count is greater than <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&gt;=(Count)</span></code> - break when the unification count is greater than or equal to <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">=:=(Count)</span></code> - break when the unification count is equal to <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">=&lt;(Count)</span></code> - break when the unification count is less than or equal to <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&lt;(Count)</span></code> - break when the unification count is less than <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">mod(M)</span></code> - break when the unification count modulo <code class="docutils literal notranslate"><span class="pre">M</span></code> is zero</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">Count</span></code> - break when the unification count is greater than or equal to <code class="docutils literal notranslate"><span class="pre">Count</span></code></p></li>
</ul>
<p>For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(planet, 41, =&lt;(2)).

Conditional breakpoint added.
yes
</pre></div>
</div>
</section>
<section id="defining-triggered-breakpoints">
<h3>Defining triggered breakpoints<a class="headerlink" href="#defining-triggered-breakpoints" title="Link to this heading"></a></h3>
<p>Conditional clause breakpoints that depend on other clause breakpoint or
on a log point are known as <em>triggered</em> clause breakpoints. The debugger
only pauses at a triggered breakpoint if the clause breakpoint or log point
it depends on is hit first. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(mars, 98, planet-76).

Triggered breakpoint added.
yes
</pre></div>
</div>
<p>In this case, the debugger will break for user interaction at the unification
port for the clause in the source file defining the <code class="docutils literal notranslate"><span class="pre">mars</span></code> object at line
98 if and only if the debugger paused earlier at the unification port for the
clause in the source file defining the <code class="docutils literal notranslate"><span class="pre">planet</span></code> category at line 76.</p>
<p>The debugger prints a <code class="docutils literal notranslate"><span class="pre">^</span></code> character at the beginning of the line for easy
recognition of triggered breakpoints.</p>
</section>
<section id="defining-context-breakpoints">
<h3>Defining context breakpoints<a class="headerlink" href="#defining-context-breakpoints" title="Link to this heading"></a></h3>
<p>A context breakpoint is a tuple describing a message execution context and
a goal:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>(<span class="nv">Sender</span>, <span class="nv">This</span>, <span class="nv">Self</span>, <span class="nv">Goal</span>)
</pre></div>
</div>
<p>The debugger pauses for user interaction whenever the breakpoint goal and
execution context subsume the goal currently being executed and its
execution context. The user may establish any number of context breakpoints
as necessary. For example, in order to call the debugger whenever a
predicate defined on an object named <code class="docutils literal notranslate"><span class="pre">foo</span></code> is called, we may define
the following context breakpoint:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(_, foo, _, _).

Spy point set.
yes
</pre></div>
</div>
<p>For example, we can spy all calls to a <code class="docutils literal notranslate"><span class="pre">foo/2</span></code> predicate with a <cite>bar</cite>
atom in the second argument by setting the condition:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(_, _, _, foo(_, bar)).

Spy point set.
yes
</pre></div>
</div>
<p>The debugger <code class="docutils literal notranslate"><span class="pre">nospy/4</span></code> predicate may be used to remove all matching
breakpoints. For example, the call:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::nospy(_, _, foo, _).

All matching context breakpoints removed.
yes
</pre></div>
</div>
<p>will remove all context breakpoints where the value of <a class="reference internal" href="../glossary.html#term-self"><span class="xref std std-term">self</span></a> is the
atom <code class="docutils literal notranslate"><span class="pre">foo</span></code>.</p>
</section>
<section id="removing-all-breakpoints">
<h3>Removing all breakpoints<a class="headerlink" href="#removing-all-breakpoints" title="Link to this heading"></a></h3>
<p>We can remove all breakpoints by using the debugger <code class="docutils literal notranslate"><span class="pre">nospyall/0</span></code> predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::nospyall.

All breakpoints removed.
yes
</pre></div>
</div>
<p>There’s also a <code class="docutils literal notranslate"><span class="pre">reset/0</span></code> predicate that can be used to reset the debugger
to its default settings and delete all defined breakpoints and log points.</p>
</section>
</section>
<section id="defining-log-points">
<h2>Defining log points<a class="headerlink" href="#defining-log-points" title="Link to this heading"></a></h2>
<p>Logtalk log points are similar to breakpoints. Therefore, the line number must
correspond to the first line of an entity clause. When the debugger reaches
a log point, it prints a log message and continues without pausing execution
for reading a port command. When the log message is an empty atom, the default
port output message is printed. When the log message starts with a <code class="docutils literal notranslate"><span class="pre">%</span></code>
character, the default port output message is printed, followed by the log
message. In these two cases, the debugger prints a <code class="docutils literal notranslate"><span class="pre">&#64;</span></code> character at the
beginning of the line for easy recognition of log points output. When the log
message is neither empty nor starts with a <code class="docutils literal notranslate"><span class="pre">%</span></code> character, the log message is
printed instead of the default port output message. In this case, the message
can contain <code class="docutils literal notranslate"><span class="pre">$KEYWORD</span></code> placeholders that are expanded at runtime. The valid
keywords are:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">PORT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">ENTITY</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">CLAUSE_NUMBER</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">FILE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">LINE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">UNIFICATION_COUNT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">INVOCATION_NUMBER</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">GOAL</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">PREDICATE</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">EXECUTION_CONTEXT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SENDER</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">THIS</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">SELF</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">METACALL_CONTEXT</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">COINDUCTION_STACK</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">THREAD</span></code></p></li>
</ul>
<p>Log points are defined using the <code class="docutils literal notranslate"><span class="pre">log/3</span></code> predicate. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::log(agent, 99, &#39;% At the secret headquarters!&#39;).
     Log point added.
yes

| ?- debugger::log(loop, 42, &#39;Message $PREDICATE from $SENDER at thread $THREAD&#39;).
     Log point added.
yes
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">logging/3</span></code> and <code class="docutils literal notranslate"><span class="pre">nolog/3</span></code> predicate can be used to, respectively, query
and remove log points. There’s also a <code class="docutils literal notranslate"><span class="pre">nologall/0</span></code> predicate that removes
all log points.</p>
<p>Note that setting a log point will remove any existing clause breakpoint for
the same location.</p>
</section>
<section id="tracing-program-execution">
<span id="programming-trace"></span><h2>Tracing program execution<a class="headerlink" href="#tracing-program-execution" title="Link to this heading"></a></h2>
<p>Logtalk allows tracing of execution for all objects compiled in debug
mode. To start the debugger in trace mode, write:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::trace.

yes
</pre></div>
</div>
<p>Next, type the query to be debugged. For example, using the <code class="docutils literal notranslate"><span class="pre">family</span></code>
example in the Logtalk distribution compiled for debugging:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- addams::sister(Sister, Sibling).
     Call: (1) sister(_1082,_1104) ?
     Rule: (1) sister(_1082,_1104) ?
     Call: (2) ::female(_1082) ?
     Call: (3) female(_1082) ?
     Fact: (3) female(morticia) ?
    *Exit: (3) female(morticia) ?
    *Exit: (2) ::female(morticia) ?
    ...
</pre></div>
</div>
<p>While tracing, the debugger will pause for user input at each leashed port,
printing an informative message. Each trace line starts with the port,
followed by the goal invocation number, followed by the goal. The invocation
numbers are unique and allow us to correlate the ports used for a goal.
In the output above, you can see, for example, that the goal <code class="docutils literal notranslate"><span class="pre">::female(_1082)</span></code>
succeeds with the answer <code class="docutils literal notranslate"><span class="pre">::female(morticia)</span></code>. The debugger also provides
determinism information by prefixing the <code class="docutils literal notranslate"><span class="pre">exit</span></code> port with a <code class="docutils literal notranslate"><span class="pre">*</span></code> character
when a call succeeds with choice-points pending, thus indicating that there
might be alternative solutions for the goal.</p>
<p>Note that breakpoints are ignored when tracing. But when a breakpoint is set
for the current predicate or clause, the debugger prints, before the port name
and number, a <code class="docutils literal notranslate"><span class="pre">+</span></code> character for predicate breakpoints, a <code class="docutils literal notranslate"><span class="pre">#</span></code> character
for clause breakpoints, a <code class="docutils literal notranslate"><span class="pre">?</span></code> character for conditional clause breakpoints,
a <code class="docutils literal notranslate"><span class="pre">^</span></code> for triggered breakpoints, and a <code class="docutils literal notranslate"><span class="pre">*</span></code> character for context
breakpoints. For example:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::spy(female/2).

yes

| ?- addams::sister(Sister, Sibling).
     Call: (1) sister(_1078,_1100) ?
     Rule: (1) sister(_1078,_1100) ?
     Call: (2) ::female(_1078) ?
  +  Call: (3) female(_1078) ?
</pre></div>
</div>
<p>To stop tracing (but still allowing the debugger to pause at the defined
breakpoints), write:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::notrace.

yes
</pre></div>
</div>
</section>
<section id="debugging-using-breakpoints">
<span id="debugging-debug"></span><h2>Debugging using breakpoints<a class="headerlink" href="#debugging-using-breakpoints" title="Link to this heading"></a></h2>
<p>Tracing a program execution may generate large amounts of debugging data.
Debugging using breakpoints allows the user to concentrate on specific
points of the code. To start a debugging session using breakpoints,
write:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- debugger::debug.

yes
</pre></div>
</div>
<p>For example, assuming the predicate breakpoint we set in the previous section
on the <code class="docutils literal notranslate"><span class="pre">female/1</span></code> predicate:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- addams::sister(Sister, Sibling).
  +  Call: (3) female(_1078) ?
</pre></div>
</div>
<p>To stop the debugger, write:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> debugger<span class="o">::</span>nodebug.

yes
</pre></div>
</div>
<p>Note that stopping the debugger does not remove any defined breakpoints or
log points.</p>
</section>
<section id="debugging-commands">
<span id="id1"></span><h2>Debugging commands<a class="headerlink" href="#debugging-commands" title="Link to this heading"></a></h2>
<p>The debugger pauses for user interaction at leashed ports when tracing
and when hitting a breakpoint. The following commands are available:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">c</span></code> — creep</dt><dd><p>go on; you may use the spacebar, return, or enter keys in alternative</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">l</span></code> — leap</dt><dd><p>continues execution until the next breakpoint is found</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">s</span></code> — skip</dt><dd><p>skips tracing for the current goal; valid at call, redo, and
unification ports</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">S</span></code> - Skip</dt><dd><p>similar to skip but displaying all intermediate ports unleashed</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">q</span></code> — quasi-skip</dt><dd><p>skips tracing until returning to the current goal or reaching
a breakpoint; valid at call and redo ports</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">r</span></code> — retry</dt><dd><p>retries the current goal but side-effects are not undone; valid at
the fail port</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">j</span></code> — jump</dt><dd><p>reads invocation number and continues execution until a port is
reached for that number</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">z</span></code> — zap</dt><dd><p>reads either a port name and continues execution until that port is
reached or a negated port name and continues execution until a port
other than the negated port is reached</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">i</span></code> — ignore</dt><dd><p>ignores goal, assumes that it succeeded; valid at call and redo ports</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">f</span></code> — fail</dt><dd><p>forces backtracking; may also be used to convert an exception into a
failure</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">n</span></code> — nodebug</dt><dd><p>turns off debugging</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">N</span></code> — notrace</dt><dd><p>turns off tracing</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">&#64;</span></code> — command; <code class="docutils literal notranslate"><span class="pre">!</span></code> can be used in alternative</dt><dd><p>reads and executes a query</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">b</span></code> — break</dt><dd><p>suspends execution and starts new interpreter; type <code class="docutils literal notranslate"><span class="pre">end_of_file</span></code>
to terminate</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">a</span></code> — abort</dt><dd><p>returns to top level interpreter</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Q</span></code> — quit</dt><dd><p>quits Logtalk</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">p</span></code> — print</dt><dd><p>writes current goal using the <code class="docutils literal notranslate"><span class="pre">print/1</span></code> predicate if available</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">d</span></code> — display</dt><dd><p>writes current goal without using operator notation</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">w</span></code> — write</dt><dd><p>writes current goal quoting atoms if necessary</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">$</span></code> — dollar</dt><dd><p>outputs the compiled form of the current goal (for low-level debugging)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">x</span></code> — context</dt><dd><p>prints execution context</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">.</span></code> — file</dt><dd><p>prints file, entity, predicate, and line number information at an
unification port</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">e</span></code> — exception</dt><dd><p>prints exception term thrown by the current goal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">E</span></code> — raise exception</dt><dd><p>reads and throws an exception term</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">=</span></code> — debugging</dt><dd><p>prints debugging information</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">&lt;</span></code> — write depth</dt><dd><p>sets the write term depth (set to <code class="docutils literal notranslate"><span class="pre">0</span></code> to reset)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">*</span></code> — add</dt><dd><p>adds a context breakpoint for the current goal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">/</span></code> — remove</dt><dd><p>removes a context breakpoint for the current goal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">+</span></code> — add</dt><dd><p>adds a predicate breakpoint for the current goal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">-</span></code> — remove</dt><dd><p>removes a predicate breakpoint for the current goal</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">#</span></code> — add</dt><dd><p>adds a breakpoint for the current clause</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">|</span></code> — remove</dt><dd><p>removes a breakpoint for the current clause</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">h</span></code> — condensed help</dt><dd><p>prints list of command options</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">?</span></code> — extended help</dt><dd><p>prints list of command options</p>
</dd>
</dl>
</section>
<section id="customizing-term-writing">
<span id="debugging-term-write"></span><h2>Customizing term writing<a class="headerlink" href="#customizing-term-writing" title="Link to this heading"></a></h2>
<p>Debugging complex applications often requires customizing term writing.
The available options are limiting the writing depth of large compound
terms and using the <code class="docutils literal notranslate"><span class="pre">p</span></code> command at a leashed port. This command uses
the <code class="docutils literal notranslate"><span class="pre">format/3</span></code> de facto standard predicate with the <code class="docutils literal notranslate"><span class="pre">~p</span></code> formatting
option to delegate writing the term to the <code class="docutils literal notranslate"><span class="pre">print/1</span></code> predicate. But
note that some backends don’t support this formatting option.</p>
<section id="term-write-depth">
<span id="debugging-term-write-depth"></span><h3>Term write depth<a class="headerlink" href="#term-write-depth" title="Link to this heading"></a></h3>
<p>The terms written by the debugger can be quite large depending on the
application being debugged. As described in the previous section, the
debugger accepts the <code class="docutils literal notranslate"><span class="pre">&lt;</span></code> command to set the maximum write term depth
for compound terms. This command requires that the used
<a class="reference internal" href="../glossary.html#term-backend-Prolog-compiler"><span class="xref std std-term">backend Prolog compiler</span></a> supports the non-standard but common
<code class="docutils literal notranslate"><span class="pre">max_depth/1</span></code> option for the <code class="docutils literal notranslate"><span class="pre">write_term/3</span></code> predicate. When the
compound term being written is deeply nested, the sub-terms are only
written up to the specified depth with the omitted sub-terms replaced
usually by <code class="docutils literal notranslate"><span class="pre">...</span></code>. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>| <span class="o">?-</span> <span class="k">write_term</span>([<span class="m">0</span>,<span class="m">1</span>,<span class="m">2</span>,<span class="m">3</span>,<span class="m">4</span>,<span class="m">5</span>,<span class="m">6</span>,<span class="m">7</span>,<span class="m">8</span>,<span class="m">9</span>], [max_depth(<span class="m">5</span>)]).

[<span class="m">0</span>,<span class="m">1</span>,<span class="m">2</span>,<span class="m">3</span>,<span class="m">4</span>|...]
yes
</pre></div>
</div>
<p>The default maximum depth depends on the backend. To print compound
terms without a depth limit, set it explicitly to zero if necessary.
The <a class="reference external" href="../../apis/debuggerp_0.html#debuggerp-0-write-max-depth-1" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">debuggerp::write_max_depth/1</span></a>
and <a class="reference external" href="../../apis/debuggerp_0.html#debuggerp-0-set-write-max-depth-1" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">debuggerp::set_write_max_depth/1</span></a>
predicates can be used to query and set the default maximum depth.</p>
</section>
<section id="custom-term-writing">
<span id="debugging-custom-term-writing"></span><h3>Custom term writing<a class="headerlink" href="#custom-term-writing" title="Link to this heading"></a></h3>
<p>The implicit use of the traditional <code class="docutils literal notranslate"><span class="pre">print/1</span></code> predicate (using the
<code class="docutils literal notranslate"><span class="pre">p</span></code> command) and the <code class="docutils literal notranslate"><span class="pre">portray/1</span></code> user-defined hook predicate
requires backend Prolog compiler support for these predicates. See
the documentation of the backend you intend to use for details. As
an example, assuming the following <code class="docutils literal notranslate"><span class="pre">portray/1</span></code> definition:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span>portray(<span class="o">e</span>(<span class="nv">V1</span>,<span class="nv">V2</span>)) <span class="o">:-</span>
    format(<span class="s">&#39;~q ---&gt; ~q~n&#39;</span>, [<span class="nv">V1</span>,<span class="nv">V2</span>]).
</pre></div>
</div>
<p>Calling the <code class="docutils literal notranslate"><span class="pre">print/1</span></code> predicate with e.g. a <code class="docutils literal notranslate"><span class="pre">e(x1,x7)</span></code> compound term
argument will output:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- print(e(x1,x7)).

x1 ---&gt; x7
yes
</pre></div>
</div>
</section>
</section>
<section id="context-switching-calls">
<span id="debugging-context"></span><h2>Context-switching calls<a class="headerlink" href="#context-switching-calls" title="Link to this heading"></a></h2>
<p>Logtalk provides a debugging control construct, <a class="reference internal" href="../refman/control/context_switch_2.html#control-context-switch-2"><span class="std std-ref">(&lt;&lt;)/2</span></a>,
which allows the execution of a query within the context of an object.
Common debugging uses include checking an object local predicates (e.g.
predicates representing internal dynamic state) and sending a message
from within an object. This control construct may also be used to write
unit tests.</p>
<p>Consider the following toy example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">object</span>(broken).

<span class="p">    :- </span><span class="k">public</span>(a<span class="o">/</span><span class="m">1</span>).

    a(<span class="nv">A</span>) <span class="o">:-</span> b(<span class="nv">A</span>, <span class="nv">B</span>), c(<span class="nv">B</span>).
    b(<span class="m">1</span>, <span class="m">2</span>). b(<span class="m">2</span>, <span class="m">4</span>). b(<span class="m">3</span>, <span class="m">6</span>).
    c(<span class="m">3</span>).

<span class="p">:- </span><span class="k">end_object</span>.
</pre></div>
</div>
<p>Something is wrong when we try the object public predicate, <code class="docutils literal notranslate"><span class="pre">a/1</span></code>:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- broken::a(A).

no
</pre></div>
</div>
<p>For helping in diagnosing the problem, instead of compiling the object in
debug mode and doing a <em>trace</em> of the query to check the clauses for the
non-public predicates, we can instead simply type:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- broken &lt;&lt; c(C).

C = 3
yes
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code> control construct works by switching the execution context
to the object in the first argument and then compiling and executing the
second argument within that context:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- broken &lt;&lt; (self(Self), sender(Sender), this(This)).

Self = broken
Sender = broken
This = broken

yes
</pre></div>
</div>
<p>As exemplified above, the <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code> control construct allows you to call
an object local and private predicates. However, it is important to
stress that we are not bypassing or defeating an object predicate scope
directives. The calls take place within the context of the specified
object, not within the context of the object making the <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code> call.
Thus, the <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code> control construct implements a form of
<em>execution-context-switching</em>.</p>
<p>The availability of the <code class="docutils literal notranslate"><span class="pre">(&lt;&lt;)/2</span></code> control construct is controlled by the
<a class="reference internal" href="programming.html#flag-context-switching-calls"><span class="std std-ref">context_switching_calls</span></a> compiler
flag (its default value is defined in the adapter files of the backend
Prolog compilers).</p>
</section>
<section id="debugging-messages">
<span id="id2"></span><h2>Debugging messages<a class="headerlink" href="#debugging-messages" title="Link to this heading"></a></h2>
<p>Calls to the <a class="reference internal" href="../refman/methods/print_message_3.html#methods-print-message-3"><span class="std std-ref">logtalk::print_message/3</span></a>
predicate where the message kind is either <code class="docutils literal notranslate"><span class="pre">debug</span></code> or <code class="docutils literal notranslate"><span class="pre">debug(Group)</span></code> are
only printed, by default, when the <a class="reference internal" href="programming.html#flag-debug"><span class="std std-ref">debug</span></a> flag is turned
on. Moreover, these calls are suppressed by the compiler when the
<a class="reference internal" href="programming.html#flag-optimize"><span class="std std-ref">optimize</span></a> flag is turned on. Note that actual printing
of debug messages does not require compiling the code in debug mode, only
turning on the <code class="docutils literal notranslate"><span class="pre">debug</span></code> flag.</p>
<section id="meta-messages">
<h3>Meta-messages<a class="headerlink" href="#meta-messages" title="Link to this heading"></a></h3>
<p>To avoid having to define <a class="reference internal" href="../refman/methods/message_tokens_2.html#methods-message-tokens-2"><span class="std std-ref">message_tokens//2</span></a> grammar rules
for translating each and every debug message, Logtalk provides default
tokenization for seven <em>meta-messages</em> that cover the most common cases:</p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">&#64;Message</span></code></dt><dd><p>By default, the message is printed as passed to the <code class="docutils literal notranslate"><span class="pre">write/1</span></code>
predicate followed by a newline.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Key-Value</span></code></dt><dd><p>By default, the message is printed as <code class="docutils literal notranslate"><span class="pre">Key:</span> <span class="pre">Value</span></code> followed by a
newline. The key is printed as passed to the <code class="docutils literal notranslate"><span class="pre">write/1</span></code> predicate
while the value is printed as passed to the <code class="docutils literal notranslate"><span class="pre">writeq/1</span></code> predicate.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Format+Arguments</span></code></dt><dd><p>By default, the message is printed as passed to the <code class="docutils literal notranslate"><span class="pre">format/2</span></code>
predicate.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">List</span></code></dt><dd><p>By default, the list items are printed indented, one per line. The
items are preceded by a dash and can be <code class="docutils literal notranslate"><span class="pre">&#64;Message</span></code>, <code class="docutils literal notranslate"><span class="pre">Key-Value</span></code>,
or <code class="docutils literal notranslate"><span class="pre">Format+Arguments</span></code> messages. If that is not the case, the item
is printed as passed to the <code class="docutils literal notranslate"><span class="pre">writeq/1</span></code> predicate.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">Title::List</span></code></dt><dd><p>By default, the title is printed, followed by a newline and the
indented list items, one per line. The items are printed as in
the <code class="docutils literal notranslate"><span class="pre">List</span></code> meta message.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[Stream,Prefix]&gt;&gt;Goal</span></code></dt><dd><p>By default, call user-defined printing <code class="docutils literal notranslate"><span class="pre">Goal</span></code> in the context of
<code class="docutils literal notranslate"><span class="pre">user</span></code>. The use of a lambda expression allows passing the message
stream and prefix. Printing the prefix is delegated to the goal.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">[Stream]&gt;&gt;Goal</span></code></dt><dd><p>By default, call user-defined printing <code class="docutils literal notranslate"><span class="pre">Goal</span></code> in the context of
<code class="docutils literal notranslate"><span class="pre">user</span></code>. The use of a lambda expression allows passing the message
stream.</p>
</dd>
</dl>
<p>Some simple examples of using these meta-messages:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>| ?- logtalk::print_message(debug, core, @&#39;Phase 1 completed&#39;).
yes

| ?- logtalk::print_message(debug, core, [Stream]&gt;&gt;write(Stream,foo)).
yes

| ?- set_logtalk_flag(debug, on).
yes

| ?- logtalk::print_message(debug, core, [Stream]&gt;&gt;write(Stream,foo)).
foo
yes

| ?- logtalk::print_message(debug, core, @&#39;Phase 1 completed&#39;).
&gt;&gt;&gt; Phase 1 completed
yes

| ?- logtalk::print_message(debug, core, answer-42).
&gt;&gt;&gt; answer: 42
yes

| ?- logtalk::print_message(debug, core, &#39;Position: &lt;~d,~d&gt;&#39;+[42,23]).
&gt;&gt;&gt; Position: &lt;42,23&gt;
yes

| ?- logtalk::print_message(debug, core, [arthur,ford,marvin]).
&gt;&gt;&gt; - arthur
&gt;&gt;&gt; - ford
&gt;&gt;&gt; - marvin
yes

| ?- logtalk::print_message(debug, core, names::[arthur,ford,marvin]).
&gt;&gt;&gt; names:
&gt;&gt;&gt; - arthur
&gt;&gt;&gt; - ford
&gt;&gt;&gt; - marvin
yes
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">&gt;&gt;&gt;</span></code> prefix is the default message prefix for <code class="docutils literal notranslate"><span class="pre">debug</span></code> messages.
It can be redefined using the
<a class="reference internal" href="../refman/methods/message_prefix_stream_4.html#methods-message-prefix-stream-4"><span class="std std-ref">logtalk::message_prefix_stream/4</span></a>
hook predicate. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>message_prefix_stream<span class="o">/</span><span class="m">4</span>).
<span class="p">:- </span><span class="k">dynamic</span>(logtalk<span class="o">::</span>message_prefix_stream<span class="o">/</span><span class="m">4</span>).

logtalk<span class="o">::</span>message_prefix_stream(debug, core, <span class="s">&#39;(dbg) &#39;</span>, user_error).
</pre></div>
</div>
</section>
<section id="selective-printing-of-debug-messages">
<h3>Selective printing of debug messages<a class="headerlink" href="#selective-printing-of-debug-messages" title="Link to this heading"></a></h3>
<p>By default, all debug messages are either printed or skipped, depending on the
<a class="reference internal" href="programming.html#flag-debug"><span class="std std-ref">debug</span></a> and <a class="reference internal" href="programming.html#flag-optimize"><span class="std std-ref">optimize</span></a> flags. When the
code is not compiled in optimal mode, the <a class="reference internal" href="../devtools/debug_messages.html"><span class="doc">debug_messages</span></a>
tool allows selective enabling of debug messages per <a class="reference internal" href="../glossary.html#term-component"><span class="xref std std-term">component</span></a> and
per debug group. For example, to enable all <code class="docutils literal notranslate"><span class="pre">debug</span></code> and <code class="docutils literal notranslate"><span class="pre">debug(Group)</span></code>
messages for the <code class="docutils literal notranslate"><span class="pre">parser</span></code> component:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>% upon loading the tool, all messages are disabled by default:
| ?- logtalk_load(debug_messages(loader)).
...

% enable both debug and debug(_) messages:
| ?- debug_messages::enable(parser).
yes
</pre></div>
</div>
<p>To enable only <code class="docutils literal notranslate"><span class="pre">debug(tokenization)</span></code> messages for the <code class="docutils literal notranslate"><span class="pre">parser</span></code> component:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>% first disable any and all enabled messages:
| ?- debug_messages::disable(parser).
yes

% enable only debug(tokenization) messages:
| ?- debug_messages::enable(parser, tokenization).
yes
</pre></div>
</div>
<p>See the tool documentation for more details.</p>
</section>
</section>
<section id="using-the-term-expansion-mechanism-for-debugging">
<span id="debugging-hooks"></span><h2>Using the term-expansion mechanism for debugging<a class="headerlink" href="#using-the-term-expansion-mechanism-for-debugging" title="Link to this heading"></a></h2>
<p>Debugging messages only output information by default. These messages can,
however, be intercepted to perform other actions. An alternative is to use
instead the <a class="reference internal" href="expansion.html#expansion-expansion"><span class="std std-ref">term-expansion mechanism</span></a> for
conditional compilation of debugging goals. For example, the
<a class="reference internal" href="../libraries/hook_objects.html"><span class="doc">hook_objects</span></a> library provides a
<a class="reference external" href="../../apis/print_goal_hook_0.html#print-goal-hook-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">print_goal_hook</span></a> object that simplifies
printing entity goals before or after calling them by simply prefixing them
with an operator. See the library and hook object documentation for details.
You can also define your own specialized hook objects for custom debugging
tasks.</p>
</section>
<section id="ports-profiling">
<span id="debugging-ports-profiling"></span><h2>Ports profiling<a class="headerlink" href="#ports-profiling" title="Link to this heading"></a></h2>
<p>The Logtalk distribution includes a <a class="reference internal" href="../devtools/ports_profiler.html"><span class="doc">ports_profiler</span></a> tool
based on the same procedure box model described above. This tool is
specially useful for debugging performance issues (e.g., due to lack of
determinism or unexpected backtracking). See the tool documentation for
details.</p>
</section>
<section id="debug-and-trace-events">
<span id="debugging-events"></span><h2>Debug and trace events<a class="headerlink" href="#debug-and-trace-events" title="Link to this heading"></a></h2>
<p>The debugging API defines two multifile predicates,
<a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-trace-event-2" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::trace_event/2</span></a> and
<a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-debug-handler-3" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::debug_handler/3</span></a> for handling
trace and debug events. It also provides a
<a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-debug-handler-1" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::debug_handler/1</span></a> multifile
predicate that allows an object (or a category) to declare itself
as a debug handler provider. The Logtalk <code class="docutils literal notranslate"><span class="pre">debugger</span></code> and  <code class="docutils literal notranslate"><span class="pre">ports_profiler</span></code>
tools are regular applications that are implemented using this API, which
can also be used to implement alternative or new debugging-related tools.
See the API documentation for details and the source code of the <code class="docutils literal notranslate"><span class="pre">debugger</span></code>
and  <code class="docutils literal notranslate"><span class="pre">ports_profiler</span></code> tools for usage examples.</p>
<p>To define a new debug handler provider, add (to an object or category) clauses
for the <code class="docutils literal notranslate"><span class="pre">debug_handler/1</span></code> and  <code class="docutils literal notranslate"><span class="pre">debug_handler/3</span></code> predicates. For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="c">% declare my_debug_handler as a debug handler provider</span>
<span class="p">:- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>debug_handler<span class="o">/</span><span class="m">1</span>).
logtalk<span class="o">::</span>debug_handler(my_debug_handler).

<span class="c">% handle debug events</span>
<span class="p">:- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>debug_handler<span class="o">/</span><span class="m">3</span>).
logtalk<span class="o">::</span>debug_handler(my_debug_handler, <span class="nv">Event</span>, <span class="nv">ExCtx</span>) <span class="o">:-</span>
    debug_handler(<span class="nv">Event</span>, <span class="nv">ExCtx</span>).

debug_handler(fact(<span class="nv">Entity</span>,<span class="nv">Fact</span>,<span class="nv">Clause</span>,<span class="nv">File</span>,<span class="nv">Line</span>), <span class="nv">ExCtx</span>) <span class="o">:-</span>
    ...
debug_handler(rule(<span class="nv">Entity</span>,<span class="nv">Head</span>,<span class="nv">Clause</span>,<span class="nv">File</span>,<span class="nv">Line</span>), <span class="nv">ExCtx</span>) <span class="o">:-</span>
    ...
debug_handler(top_goal(<span class="nv">Goal</span>, <span class="nv">TGoal</span>), <span class="nv">ExCtx</span>) <span class="o">:-</span>
    ...
debug_handler(goal(<span class="nv">Goal</span>, <span class="nv">TGoal</span>), <span class="nv">ExCtx</span>) <span class="o">:-</span>
    ...
</pre></div>
</div>
<p>Your debug handler provider should also either automatically call the
<a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-activate-debug-handler-1" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::activate_debug_handler/1</span></a>
and <a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-deactivate-debug-handler-0" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::deactivate_debug_handler/0</span></a>
predicate or provide public predicates to simplify calling these predicates.
For example:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">public</span>(start<span class="o">/</span><span class="m">0</span>).
start <span class="o">:-</span>
   logtalk<span class="o">::</span>activate_debug_handler(my_debug_handler).

<span class="p">:- </span><span class="k">public</span>(stop<span class="o">/</span><span class="m">0</span>).
stop <span class="o">:-</span>
   logtalk<span class="o">::</span>deactivate_debug_handler.
</pre></div>
</div>
<p>If you only need to define a trace event handler, then simply define clauses
for the <a class="reference external" href="../../apis/logtalk_0.html#logtalk-0-trace-event-2" title="(in Logtalk APIs v3.93.0)"><span class="xref std std-ref">logtalk::trace_event/2</span></a> multifile
predicate:</p>
<div class="highlight-logtalk notranslate"><div class="highlight"><pre><span></span><span class="p">:- </span><span class="k">multifile</span>(logtalk<span class="o">::</span>trace_event<span class="o">/</span><span class="m">2</span>).
<span class="p">:- </span><span class="k">dynamic</span>(logtalk<span class="o">::</span>trace_event<span class="o">/</span><span class="m">2</span>).

<span class="c">% the Logtalk runtime calls all defined logtalk::trace_event/2 hooks using</span>
<span class="c">% a failure-driven loop; thus we don&#39;t have to worry about handling all</span>
<span class="c">% events or failing after handling an event to give other hooks a chance</span>
logtalk<span class="o">::</span>trace_event(fact(<span class="nv">Entity</span>, <span class="nv">Fact</span>, <span class="nv">N</span>, <span class="nv">_</span>, <span class="nv">_</span>), <span class="nv">_</span>) <span class="o">:-</span>
    ...
logtalk<span class="o">::</span>trace_event(rule(<span class="nv">Entity</span>, <span class="nv">Head</span>, <span class="nv">N</span>, <span class="nv">_</span>, <span class="nv">_</span>), <span class="nv">_</span>) <span class="o">:-</span>
    ...
</pre></div>
</div>
</section>
<section id="source-level-debugger">
<span id="debugging-source-level-debugger"></span><h2>Source-level debugger<a class="headerlink" href="#source-level-debugger" title="Link to this heading"></a></h2>
<p>A minimal source-level debugger is provided by the Logtalk for VSCode
extension: when debugging in the integrated terminal using the <code class="docutils literal notranslate"><span class="pre">debugger</span></code>
tool, the current clause (at leashed unification ports) is shown in the
active editor window. The extension can also be used with VSCodium. See
its documentation for more details.</p>
</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="documenting.html" class="btn btn-neutral float-left" title="Documenting" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="performance.html" class="btn btn-neutral float-right" title="Performance" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 1998-2025, Paulo Moura.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>